home *** CD-ROM | disk | FTP | other *** search
/ Mac-Source 1994 July / Mac-Source_July_1994.iso / C and C++ / Libraries / File Dropper / Read Me - File Dropper < prev   
Encoding:
Text File  |  1993-07-12  |  12.6 KB  |  269 lines  |  [TEXT/KAHL]
  1.                                     File Dropper 1.1ß2
  2.                                     Written by Troy Anderson
  3.  
  4.                     Copyright © 1992-1993, Troy Anderson; All Rights Reserved
  5.  
  6.                                     What Is This Thing?
  7.  
  8. File Dropper is a THINK C library that implements an application that you can drop files or 
  9. folders onto to do batch operations on.  It handles the getting of the AppleEvents if 
  10. running under System 7, the main event loop, and the menus.  You need only write the code 
  11. that acts on the individual files.
  12.  
  13.  
  14.                                     New Features in 1.1ß2
  15.                                     
  16. • Built "File Dropper π" in THINK C 6.0
  17. • The cursor is NOT reset to an arrow after each call to SetStatusPercentage.
  18. • If you return FALSE from the eStartup, eSFInitialize, or eAEInitialize messages, File Dropper 
  19.   will send you an eQuitting message and quit the application.
  20. • If you return FALSE from the eValidate message, File Dropper will skip any remaining files
  21.   in the current batch.
  22. • If you return FALSE from an eDispose message, File Dropper will send you an eQuitting message
  23.   and quit the application.  Returning TRUE from an eDispose message will cause File Dropper to
  24.   continue running.  This behavior does NOT depend upon which of eSFInitialize or eAEInitialize
  25.   was sent to you.
  26. • If you return TRUE from an eQuitting message, the File Dropper quits.  On the other hand, if 
  27.   you return FALSE from an eQuitting message, File Dropper will quit.
  28. • If you want the source code to File Dropper, send me money (see the end of this document).
  29. • Added an eUserCancelled message for when the user clicks Cancel in the status box.
  30. • Added an eIdle message.
  31. • Added the ChangeStatusMessage function that lets you change the message in the status dialog
  32.   on the fly, during your processing of the file.
  33. • Changed some things internally, so you can NOT call InstallCustomGetFSSpecFunc,
  34.   InstallCustomFileFilterFunc, or InstallCustomDialogHookFunc from an eSFInitialize or 
  35.   eAEInitialize message any more, just from eStartup.
  36. • Fixed a bug in the ErrorAlert function so that text relating to the error as well as the
  37.   word "Error." show up in the dialog.
  38. • Made it simpler to support AboutBox functionality.  You just put text in STR# resource 129, and
  39.   it will be displayed in the warp stars.  To enable this feature, return TRUE from the 
  40.   eDoAboutBox message.
  41.                                     
  42.                                     
  43.                                     New Features in 1.1ß1
  44.                                     
  45. • Now you can specify if you want the status dialog displayed while you are working on the files,
  46.   wether they were selected with SFGetFile or an AppleEvent.
  47. • There is a progress bar like Finder 7's that you update by specifying how far along you are with
  48.   a percentage (0 - 100).  You can elect to turn this option off, too.
  49.  
  50.     
  51.                                     How Do I Implement My Part?
  52.  
  53. All definitions and prototypes that you need are in the "FD Interface.h" file.  You simply write
  54. the ModuleMain function, and let the library do the rest.
  55.  
  56. The ModuleMain function takes two parameters, a short and a ModuleDataRec.  The short is a 
  57. message that tells you why you were called.  The ModuleDataRec is a record that contains data 
  58. that you may need in order to perform the required task.  It returns a Boolean value.  The
  59. returned value is ignored in all but one case, when you are sent an eValidateFile message.  See
  60. the eValidateFile message description below for details.
  61.  
  62. Be sure that all of the resources in "File Dropper Starter π.rsrc" are included in the resource
  63. file for your project.  It's easiest to make a copy of "File Dropper Starter π.rsrc" and use it.
  64.  
  65. To allow dropping of different types of files/folders/volumes onto your application, change the
  66. 'FREF' resource to include the types of files you can act on.  There are some special types that
  67. correspond to folders, volumes, etc.  For a more indepth discussion of this, see section 9-17 
  68. of Inside Macintosh Volume VI.  See section 9-30 for a list of file types you can use for folders,
  69. floppy disks, the trash, etc.
  70.  
  71. Be sure to change the creator type in the Set Project Type… menu of THINK C, and the creator 
  72. type in the resource file, and to give your application a cool icon.
  73.  
  74.                                     What Is A ModuleDataRec?
  75.  
  76. The ModuleDataRec is defined as follows:
  77.  
  78. typedef struct {
  79.     FSSpec    *theFile;        // a file specification
  80.     long    refcon;            // a reference constant for you to do with what you will
  81.     } ModuleDataRec;
  82.  
  83.                                     What Are The Messages?
  84.                                     
  85. There are 6 possible messages, they are eStartup, eAEInitialize, eSFInitialize, 
  86. eValidateFile, eProcessFile, eDispose, and eQuitting.
  87.  
  88. You get the messages in this order:
  89.  
  90. eStartup
  91.     This tells you that the program just started up.  You get this message exactly once.
  92.     In the ModuleDataRec, theFile and refcon are initialize to NULL and 0 respectively.  You
  93.     are free to use refcon for anything you choose, including allocating a handle and saving
  94.     its value in refcon so you can have additional storage.  Nothing really precludes you from
  95.     having global data hanging around, but someday this thing may evolve into a CODE resource
  96.     interface that will make having globals more difficult. I never touch refcon, so what you
  97.     do with it is up to you.
  98.     
  99.     This is a where you should call the customization routines like SetStatusParams,
  100.     InstallCustomGetFSSpecFunc,    InstallCustomFileFilterFunc, or InstallCustomDialogHookFunc.
  101.     Although it's all right to call SetStatusParams from eAEInitialize or eSFInitialize as well.
  102.     
  103.     Return TRUE if everything you did turned out OK (e.g. you got all the memory you asked for).
  104.     Returning FALSE causes File Dropper to send you an eQuitting message and quit.
  105.     
  106. eAEInitialize or eSFInitialize
  107.     This tells you that a file/folder/volume has been selected by the user to be acted upon.
  108.  
  109.     eAEInitialize indicates that the file/folder/volume was "dropped" onto the application or
  110.     sent to it using an 'odoc' AppleEvent.
  111.  
  112.     eSFInitialize indicates that the file (of folder or volume if you've installed a Custom
  113.     GetFSSpec Function using InstallCustomGetFSSpecFunction()) was selected by the user using
  114.     a standard get file dialog.  NOTE: You get this message AFTER the user selects the file.
  115.     If you want to install a custom get file using InstallCustomGetFSSpecFunc,
  116.     InstallCustomFileFilterFunc, or InstallCustomDialogHookFunc, do it in eStartup, not here.
  117.  
  118.     
  119.     It is handy to know wether the file was obtained from a "drop" or from a GetFile dialog
  120.     if, for instance, you have options based on keys pressed when "dropped," but not when 
  121.     obtained from a dialog.
  122.     
  123.     You will receive one of these messages for each batch of files to be processed,
  124.     before you are told to do any processing.
  125.     
  126.     In ModuleDataRec, theFile is meaningless during this message.
  127.     
  128.     Return TRUE if everything you did as a result of this message was OK.
  129.     Returning FALSE causes File Dropper to send you an eQuitting message and quit.
  130.     
  131. eValidateFile
  132.     This asks you if the file specified in the theFile parameter of the ModuleDataRec record
  133.     is valid for you to work on.  I.E. should eProcessFile be sent?  Return TRUE if you want
  134.     to process it, otherwise return FALSE.
  135.     
  136. eProcessFile
  137.     This tells you to do your thing.  You get this message for each file in the batch.  The
  138.     ModuleDataRec will contain a pointer to the FSSpec for the file that you are to process
  139.     in the theFile parameter.
  140.     
  141.     If you return TRUE and there are any more files to process, you will be sent the next
  142.     file in the batch.  If you return FALSE, no more files will be sent to you for the
  143.     current batch.
  144.  
  145. eUserCancelled
  146.     This tells you that the user clicked Cancel in the status dialog while a file was being
  147.     processed.  The ModuleDataRec will contain a pointer to the FSSpec for the file that
  148.     was being processed in the theFile parameter.  Since File Dropper handles the status 
  149.     dialog only when you call SetStatusPercentage, you will get this message while in a
  150.     call to SetStatusPercentage, thus your ModuleMain must be reentrant with respect to the
  151.     eUserCancelled case.
  152.     
  153.     If you return TRUE, you will get an eDispose message, followed by an eQuitting message, 
  154.     then File Dropper will ExitToShell.  Returning FALSE causes File Dropper to act as if 
  155.     the Cancel button was not pressed.  I suggest you always return TRUE unless you have a 
  156.     really good reason not to, like you are keeping track of the fact that the user cancelled
  157.     and will return FALSE from the next eProcessFile.
  158.  
  159. eDispose
  160.     This tells you that the batch is finished.  This balances out the eAEInitialize or 
  161.     eSFInitialize messages.  It gives you a chance to clean up any data structures you
  162.     set up there.
  163.     
  164.     Return FALSE if you want File Dropper to send you an eQuitting message and quit.  
  165.     Return TRUE if you want File Dropper to keep running.
  166.     
  167.     In ModuleDataRec, theFile is meaningless.
  168.  
  169. eQuitting
  170.     This tells you that the application is about to quit.  If you need to save or flush anything,
  171.     this is the time to do it.
  172.     
  173.     The return value is ignored for this call.
  174.     
  175.     In ModuleDataRec, theFile is meaningless.
  176.  
  177. eIdle
  178.     You get one of these for each NULL event File Dropper gets.  You won't get one while you're
  179.     processing a file.
  180.  
  181. eDoAboutBox
  182.     If you return TRUE from this message, I will handle the about box by reading from the STR#
  183.     number 129.  I will read all strings starting with number 1 in that resource and display
  184.     them in the about box.  Only up to about 6 strings will actually fit in the about box. 
  185.     
  186.     If you return FALSE from the eDoAboutBox message, I will assume that you handled the about
  187.     box and do nothing.
  188.     
  189.  
  190. In summary:
  191.  
  192. eStartup
  193.     REPEAT AS LONG AS USER SELECTS THINGS FROM THE GET FILE DIALOG
  194.         eSFInitialize
  195.             REPEAT FOR EACH FILE
  196.                 eValidateFile
  197.                 eProcessFile    (if validation succeeded)
  198.             END REPEAT
  199.         eDispose
  200.         eIdle (until the user selects Open, Quit, or more files get dropped on)
  201.     END REPEAT*
  202. eQuitting
  203.  
  204. * You can make it so that File Dropper quits after the first 
  205.   selection/processing of a file.  See the section on eDispose.
  206.  
  207. -OR-
  208.  
  209. eStartup
  210.     eAEInitialize
  211.         REPEAT FOR EACH FILE
  212.             eValidateFile
  213.             eProcessFile    (if validation succeeded)
  214.         END REPEAT
  215.     eDispose
  216.     eIdle (until the user selects Open, Quit, or more files get dropped on)
  217. eQuitting†
  218.  
  219. † You can make it so that File Dropper stays open until the user actually 
  220.   selects Quit from the File menu or a 'quit' AppleEvent comes in.  See
  221.   the section on eDispose.
  222.  
  223.  
  224.  
  225.                                 About The Guy Who Wrote It
  226.                                     
  227. This was written by me, Troy Anderson, after a comment from a user of Marker that wanted source
  228. so he could do something else with the files that were dropped on the application.  This allows
  229. you to create little utility applications that do fun things.  If you really like this, and you
  230. write software, send me a copy of it.  Thanks.
  231.  
  232. Internet:        tla@CRL.com
  233. Compuserve:        70410,1407
  234. America Online: Troy A1
  235. US Mail:        Troy Anderson
  236.                 5550 East Roadrunner Road
  237.                 Paradise Valley, AZ  85253
  238.             
  239.                                 
  240.                                 I Want The Source Code!
  241.                                 
  242. If you want the source code (10 commented source files) including AppleEvent sending and receiving,
  243. handling, file manipulation, Standard file customization, finder-like status bar, and the warp
  244. stars about box effect, send me a U.S. check for $35 and a self addressed envelope that will hold
  245. a disk or your Compuserve or America Online address or send $30 and your internet address and I'll
  246. send you the latest version of the source code including at least everything mentioned in this
  247. exceedingly long sentence.  See paragraph three in the Legal Stuff section for what you can do
  248. once you have the souce code, besides reading it.
  249.  
  250.  
  251.                                     Legal Stuff
  252.                                     
  253. If you like it, let me know.  If you want to pay for it, send me money.  If there are bugs, tell
  254. me, I may actually fix them.  Every effort has been made to ensure that this software
  255. works as specified, but it has no warranties, expressed or implied, as to its usefulness, 
  256. stability, or functionalty.  Use this software at your own risk. 
  257.  
  258. You may use and distribute applications made with File Dropper at no charge, but you may not
  259. sell them, or collect money for their distribution (normal disk duplication fees excepted).  
  260. Anyone wishing to distribute an application using File Dropper along with any commercial or 
  261. shareware software package may do so only with my express written consent.
  262.  
  263. If you receive the source code to File Dropper, you may modify it and use it in your own projects
  264. and distribute them as long as they are free of any charge and my name is displayed in the About
  265. Box or other equally accessable place.  If the application you are distributing is a File Dropper
  266. type application, you must either leave the "About YourAppName..." menu item and functionality in 
  267. place, although you can change the menu item's name to be more appropriate, or give me credit in
  268. your custom about box, including "This application is based on the File Dropper by Troy Anderson"
  269. and "File Dropper © 1993 Troy Anderson".